Update EIP-5792: Propose changes to EIP-5792 atomicity #9529

cryptotavares · 2025-03-25T01:23:57Z

Goal

Improve the current API to support, in an expressive and simple way, both atomic and non-atomic batch requests.

Context

The atomic topic has been heavily discussed within the latest 5792 calls. And it was agreed that in order to foster broader adoption of the proposed wallet APIs specified in this spec, it should support both atomic and non-atomic batches.

Changes

Introduce a top level atomic property across the different API methods (wallet_sendCalls, wallet_getCallsStatus, wallet_getCapabilities).

Wallets express the atomic values it supports via wallet_getCapabilities.

~~The strict, loose and none atomicity concepts are directly taken from the flow-control capability proposed by @SamWilsn.~~

eth-bot · 2025-03-25T01:24:18Z

✅ All reviewers have approved.

EIPS/eip-5792.md

lukasrosario · 2025-03-25T14:36:09Z

EIPS/eip-5792.md

+### `atomicity` Capability
+
+Like the illustrative examples given above and other capabilities to be defined in future EIPs, the capability to specify how calls delivered via the above-defined methods should be executed can be expressed  as `atomic` or `non-atomic`.
+
+This capability is expressed separately on each chain and should be interpreted as a guarantee only for batches of transactions on that chain


is this supposed to be how the wallet expresses the values for atomicity it supports? if so think we could reword to make a bit clearer, lmk if you had something else in mind though

Yes that was the idea...
I have kept the details on the how the flow is controlled, because I believe that those are implementation details that can be better expressed via the flow-control capability. I have prioritised simplicity over configuration. Meaning that the Wallet can implement the both the atomic and non-atomic option as it sees fit. As long as it respects the atomicity for the calls execution.

Re-worded it a bit. Let me know what you think.

wilsoncusack · 2025-03-25T18:46:18Z

EIPS/eip-5792.md

  id?: string;
  from?: `0x${string}`;
  chainId: `0x${string}`; // Hex chain id
+  atomicity: "atomic" | "nonAtomic" | "any";


Seems like it would be nice to have atomicPreferred for when it's preferred but not required

Would it ever not be preferred? 🤔 Both from Wallet and App perspective..

The idea for any, is for when an App does not care about execution, but really just wants to send a batch of transactions to the wallet.

Also I have not added the option for the Wallet to support both non-atomic and atomic execution for the same chain (see here). The reason was exactly that if atomic is available then the calls will be executed atomically.
Do you think that there's a case where:

A wallet would prefer sequential execution on a chain where it supports atomic execution?

An App would prefer sequential execution when it can ask for atomic execution?

And if yes, do you feel that it should be included in the spec, or that it is specific enough that it could be its own capability (defined as a different erc)?

Agree that I can't think of a situation where atomic wouldn't be preferred - in which case I think maybe atomic | any might be sufficient (or a boolean as @matthewwalsh0 suggests below?)

EIPS/eip-5792.md

Co-authored-by: Matthew Walsh <matthew.walsh@consensys.net>

azf20

Many thanks for the updates

azf20 · 2025-03-26T12:56:55Z

EIPS/eip-5792.md

  id?: string;
  from?: `0x${string}`;
  chainId: `0x${string}`; // Hex chain id
+  atomicity: "atomic" | "nonAtomic" | "any";


Agree that I can't think of a situation where atomic wouldn't be preferred - in which case I think maybe atomic | any might be sufficient (or a boolean as @matthewwalsh0 suggests below?)

EIPS/eip-5792.md

SamWilsn · 2025-03-28T15:40:22Z

EIPS/eip-5792.md

+* If a wallet executes multiple calls **atomically** in a single transaction, `wallet_getCallsStatus` MUST return an object with a `receipts` field that contains a single transaction receipt, corresponding to the transaction in which the calls were included. It also MUST be explicit and return an `atomicity` field set to `"strict"`.
+* If a wallet executes multiple calls **atomically** in a multiple transactions as part of a bundle, `wallet_getCallsStatus` MUST return an object with a `receipts` field that contains **an array of receipts** for all transactions. It also MUST be explicit and return a `atomicity` field set to `"loose"`.
+* If a wallet executes multiple calls **non-atomically**, `wallet_getCallsStatus` MUST return an object with a `receipts` field that contains **an array of receipts** for all transactions containing batch calls that were included onchain. This includes the batch calls that were included on-chain but eventually reverted. It also MUST be explicit and return a `atomicity` field set to `"none"`.


Why specify anything about the structure of the receipt field? It seems overly restrictive. What benefits does it bring?

Might be a question for @lukasrosario too.

The benefit was to try to make the reasoning about the receipts structure simple and comprehensive enough for dapps. Reduce the complexity and any ambiguity that might exist. However I feel that we can make it less restrictive, as I agree with your previous comment about strict being executed as multiple transactions. At that point, then the receipts field can have:

a single or multiple transactions for strict atomicity

multiple transactions for loose and none

EIPS/eip-5792.md

SamWilsn · 2025-03-29T03:18:32Z

EIPS/eip-5792.md

+* When atomicity is set to `none`:
+  * MAY execute each call as a single transaction.
+  * MAY execute each call as a single transaction, as part of a bundle that is executed atomically.
+  * MAY execute all calls sequentially without any atomicity guarantees.


This doesn't specify the behaviour on failed transactions.

Do you think that we need to specify the behaviour for failed transactions submitted sequentially?

I was thinking that we could leave that for the wallets to decide. Meaning that in the simplest form, an app that does not care about atomic execution, will need to go through the receipts and figure out the batch was executed. I would leave further specifications to a different capability (like the flow-control one).

Co-authored-by: Francisco Giordano <fg@frang.io>

Co-authored-by: Sam Wilson <57262657+SamWilsn@users.noreply.github.com>

EIPS/eip-5792.md

lukasrosario · 2025-04-02T07:46:17Z

EIPS/eip-5792.md

 ## Security Considerations

-App developers MUST NOT assume that all calls will be sent in a single transaction if they were submitted to a wallet with a capability defining how to execute the calls non-atomically. The exact behavior of non-atomically executed calls is to be defined in separate ERCs.
+Regardless of the `atomic` value specified, App developers MUST NOT assume that all calls will be sent in a single transaction.


an example like the one you shared with me would be good to add here -- i think it might not be immediately obvious why this would be the case.

The definition above states:

MUST execute all calls atomically—either all calls execute successfully or no material effects appear on chain.
Can you give an example of an implementation of "atomic:true" that matches that assert, and still is not on a single transaction ?

@drortirosh see my comment here

Co-authored-by: Jakub Witczak <jakubwitczak6@gmail.com>

bumblefudge · 2025-04-04T08:54:03Z

EIPS/eip-5792.md

+```json
+{
+  "0x2105": {
+    "atomic": true


sorry if i missed something, but why is atomic differently-shaped than other caps, i.e. why are these
"atomic": true
instead of
"atomic": { "supported": true }
like the other examples above?

The other capabilities highlighted in the spec are just examples of what we might have, but they are not real capabilities defined anywhere. Also there is no specified type for the capability itself (currently is specified as any). Only for the getCapabilities response:

type GetCapabilitiesResult = Record<`0x${string}`, <Record<string, any>>; // Hex chain id

I opted for a simple boolean just for simplicity.

Do you think we should change the capability type from any to be something more structured?
My personal opinion is that we should keep it unconstrained, because adopting a capability will be an intended action. So app and wallet will need to specifically develop and implement such capability. And if that is the case, then we should, at least for now, not constrain capability authors with a specified schema/structure.

What do you think?

i think we should keep the GetCapabilitiesResult type as is but agree we should conform to "atomic": { "supported": true }. i dont think that format needs to be a strict requirement, but i dont see why we'd stray from it

bumblefudge

see in-line nit about shape of "atomic" capability

lukasrosario

lfg

eth-bot

All Reviewers Have Approved; Performing Automatic Merge...

Propose changes to EIP-5792 atomicity

27ef13a

github-actions bot added c-update Modifies an existing proposal s-review This EIP is in Review t-interface labels Mar 25, 2025

eth-bot added the a-review Waiting on author to review label Mar 25, 2025

eth-bot changed the title ~~Propose changes to EIP-5792 atomicity~~ Update EIP-5792: Propose changes to EIP-5792 atomicity Mar 25, 2025

fix: linting

bae1bb8

lukasrosario reviewed Mar 25, 2025

View reviewed changes

EIPS/eip-5792.md Outdated Show resolved Hide resolved

lukasrosario reviewed Mar 25, 2025

View reviewed changes

cryptotavares added 2 commits March 25, 2025 18:18

fix: camelCase non-atomic value

acda3a0

chore: improve atomicity capability wording

f9dc3d9

wilsoncusack reviewed Mar 25, 2025

View reviewed changes

vandan mentioned this pull request Mar 26, 2025

Add EIP-5792 methods MetaMask/api-specs#284

Merged

matthewwalsh0 reviewed Mar 26, 2025

View reviewed changes

cryptotavares and others added 2 commits March 26, 2025 11:45

Update EIPS/eip-5792.md

e219c0d

Co-authored-by: Matthew Walsh <matthew.walsh@consensys.net>

Update EIPS/eip-5792.md

f2c9125

Co-authored-by: Matthew Walsh <matthew.walsh@consensys.net>

azf20 reviewed Mar 26, 2025

View reviewed changes

cryptotavares added 3 commits March 26, 2025 23:49

chore: attempt to include loose atomicity

7c51e5a

fix: improve wording on atomicity special capability

2c6145e

chore: improve getCallStatus loose atomicity case

4e6c4c6

lukasrosario reviewed Mar 28, 2025

View reviewed changes

EIPS/eip-5792.md Outdated Show resolved Hide resolved

frangio reviewed Mar 28, 2025

View reviewed changes

EIPS/eip-5792.md Outdated Show resolved Hide resolved

frangio reviewed Mar 28, 2025

View reviewed changes

EIPS/eip-5792.md Outdated Show resolved Hide resolved

SamWilsn reviewed Mar 28, 2025

View reviewed changes

SamWilsn reviewed Mar 29, 2025

View reviewed changes

cryptotavares and others added 4 commits March 31, 2025 17:43

Update EIPS/eip-5792.md

17974f4

Co-authored-by: Francisco Giordano <fg@frang.io>

Update EIPS/eip-5792.md

30ec888

Co-authored-by: Francisco Giordano <fg@frang.io>

Update EIPS/eip-5792.md

c733bcb

Co-authored-by: Sam Wilson <57262657+SamWilsn@users.noreply.github.com>

Update EIPS/eip-5792.md

dc445c8

Co-authored-by: Sam Wilson <57262657+SamWilsn@users.noreply.github.com>

cryptotavares and others added 2 commits April 1, 2025 11:03

Update EIPS/eip-5792.md

2d5aa69

Co-authored-by: Sam Wilson <57262657+SamWilsn@users.noreply.github.com>

simplify proposal to atomic boolean

aa5a91a

jakubuid reviewed Apr 2, 2025

View reviewed changes

EIPS/eip-5792.md Outdated Show resolved Hide resolved

jakubuid reviewed Apr 2, 2025

View reviewed changes

EIPS/eip-5792.md Outdated Show resolved Hide resolved

lukasrosario reviewed Apr 2, 2025

View reviewed changes

cryptotavares and others added 3 commits April 2, 2025 12:54

Update EIPS/eip-5792.md

c2a1039

Co-authored-by: Jakub Witczak <jakubwitczak6@gmail.com>

improve wallet sendCalls readability

d46bc02

add example of multi transactions atomic

228de83

cryptotavares marked this pull request as ready for review April 3, 2025 13:33

cryptotavares requested a review from eth-bot as a code owner April 3, 2025 13:33

bumblefudge reviewed Apr 4, 2025

View reviewed changes

bumblefudge suggested changes Apr 4, 2025

View reviewed changes

rename to atomicRequired in sendCalls

cce8c89

azf20 mentioned this pull request Apr 4, 2025

update for atomic core capability lukasrosario/eip-5792-site#12

Merged

align atomic capability type with examples

585a8cd

lukasrosario approved these changes Apr 4, 2025

View reviewed changes

eth-bot enabled auto-merge (squash) April 4, 2025 15:05

eth-bot approved these changes Apr 4, 2025

View reviewed changes

eth-bot merged commit 8e9fe8b into ethereum:master Apr 4, 2025
11 checks passed

Update EIP-5792: Propose changes to EIP-5792 atomicity #9529

Update EIP-5792: Propose changes to EIP-5792 atomicity #9529

Uh oh!

Conversation

cryptotavares commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goal

Context

Changes

Uh oh!

eth-bot commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

azf20 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bumblefudge Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bumblefudge left a comment

Choose a reason for hiding this comment

Uh oh!

lukasrosario left a comment

Choose a reason for hiding this comment

Uh oh!

cryptotavares commented Mar 25, 2025 •

edited

Loading

eth-bot commented Mar 25, 2025 •

edited

Loading

bumblefudge Apr 4, 2025 •

edited

Loading